home *** CD-ROM | disk | FTP | other *** search
/ Celestin Apprentice 2 / Apprentice-Release2.iso / Source Code / Libraries / Graphic Elements 2 / ReadMe — Version 1.5 < prev    next >
Encoding:
Text File  |  1994-06-23  |  4.8 KB  |  108 lines  |  [TEXT/MMCC]
  1. 6/23/94
  2.  
  3. CHANGES AND NEW FEATURES IN GRAPHIC ELEMENTS VERSION 1.5
  4.  
  5. 1.    NewGEWorld now takes a GrafPtr instead of a CWindowPtr as a parameter. This change
  6.     change was made for increased generality, and should not affect the operation of
  7.     your code in any way.
  8.     
  9. 2.    A new facility has been added to allow elements to clean up after themselves when
  10.     they are disposed. This is for use by Graphic elements which allocate memory
  11.     on the heap during initialization, and assign pointers to that memory to their
  12.     drawData and/or changeData fields. Such an element may now provide a CleanupProc
  13.     to free up this memory when it is freed.
  14.     
  15.     This facility includes the following:
  16.     
  17.     A function prototype,
  18.     
  19.     typedef pascal void (*CleanupProc)(GEWorldPtr world, GrafElPtr element);
  20.     
  21.     An added field in the basic Graphic Element structure,
  22.     
  23.     element->cleanupProc;
  24.     
  25.     And a function for setting this field, 
  26.     
  27.     void SetCleanupProc(GEWorldPtr world, OSType elementID, CleanupProc elemCleanup);
  28.     
  29. 3.    GEWorlds are now scalable at creation. This means that the same graphics and the
  30.     same functions for initializing, moving, and otherwise acting upon Graphic Elements
  31.     can be used in differently-size windows or other grafports with very few changes
  32.     in existing code.
  33.     
  34.     A parameter "scale" has been added to NewGEWorld():
  35.     
  36.     GEWorldPtr NewGEWorld(GrafPtr worldPort, Rect *worldRect, 
  37.                                         Fixed scale, CTabHandle worldColors);
  38.                                         
  39.     Scale is a standard fixed-point number in which the high-order word represents an
  40.     integer and the low-order word represents a fraction. Scaling is done with reference
  41.     to worldRect, which should be a rectangle the "normal" one-to-one size of this
  42.     GEWorld. The constant scaleOneToOne is provided for the usual case of creating a
  43.     world the same size as worldRect.
  44.     
  45.     In general, individual Graphic Elements, their positions, and their actions are 
  46.     automatically scaled to the world they are in. However, sometimes during the creation
  47.     of a scene, it is necessary to position a newly-created element in relation to one
  48.     which already exists. For example, in one of the example programs, the bottom right 
  49.     corner of the cannon's smoke is 16 pixels right and 16 pixels down from the top left 
  50.     corner of the cannon, when both are drawn at full size. 
  51.     
  52.     When the smoke is created, the cannon's position has already been scaled to its
  53.     world, so we must position the smoke in relation to the cannon's *actual* 
  54.     coordinates within the world. However, the 16-pixel offset will be wrong for
  55.     worlds which are smaller or larger than the "actual size" of the graphics.
  56.     
  57.     The following changes have been made in Graphic Elements to handle this situation:
  58.     
  59.     The PtrMoveTo() function now has an additional Boolean parameter, doScale:
  60.     
  61.     void PtrMoveElementTo(GEWorldPtr world, GrafElPtr element, 
  62.                                     short h, short v, Boolean doScale);
  63.     
  64.     If doScale is true, h and v are scaled to the coordinate system of world before
  65.     the move. Otherwise, they are accepted as absolute pixel coordinates within the
  66.     world.
  67.     
  68.     To handle cases such as the smoke's 16-pixel offset from the top left of the cannon,
  69.     Graphic Elements provides the function:
  70.     
  71.     short ScaleToWorld(GEWorldPtr world, short value);
  72.  
  73.     This function returns value scaled to the coordinate system of world.
  74.     
  75. 4)    RectHeight(Rect *r) and RectWidth(Rect *r) have been added to the services provided
  76.     by the Rects module.
  77.     
  78. 5)    Collision handling has been enhanced. For most Graphic Elements, the fact that they
  79.     have collided with another elements is enough: they explode, bounce, or perform some
  80.     other single action in response to the collision.
  81.     
  82.     Others, however, may need to perform an action repeatedly for as long as the collision
  83.     state continues, or perform one action when the collision state begins and another
  84.     when it ends. Graphic Elements now makes the following provisions for these cases:
  85.     
  86.     An enumerated type has been added:
  87.     
  88.     typedef enum {collisionBegin, collisionContinue, collisionEnd} CollisionPhase;
  89.     
  90.     The prototype of a CollisionProc has been updated to include a parameter of this type:
  91.     
  92.     typedef pascal void (*CollisionProc)(GEWorldPtr world, GrafElPtr element, 
  93.                                     GEDirection dir, CollisionPhase phase, GrafElPtr hitElement);
  94.                                     
  95.     An element's collision function will be called once when the collision first occurs,
  96.     repeatedly for as long as it remains in a collision state with another element, and once
  97.     when the collision condition ends.
  98.     
  99. 6)    A very general special-effects module has been added. This module is provided in
  100.     linkable-library form in GELib:GEExtras.lib (or GEExtrasCW.lib). Example special
  101.     effects are included in Extras:SFXProcs.c. Complete documentation for this module
  102.     will be available at a later date. For now, see the header files and examples in
  103.     GEDemo and GETest, along with the sample effects in SFXProcs.c.
  104.     
  105.  
  106.     
  107.  
  108.